The following guide is to help the deployment of an AWS SAML configuration as the authentication provider for Pyramid. AWS is very similar to generic SAML.
Note: This feature is only available with Enterprise licensing.
Important: If Same Site client security is set to Strict when using SAML authentication, this may cause a loop redirect between Pyramid and the SAML provider, as cookies are prevented from working across different web domains. This shouldn't be an issue if your SAML provider and Pyramid are within the same web domain.
AWS SAML Setup
Configure a SAML Application
Start by configuring your AWS SAML application. Login to AWS and add an application: AWS > IAM Identity Center > Add application
Choose the following options:
- System preferences: I have an application I want to set up
- Application type: SAML 2.0
Configure application
Display name: Give your application a name
Under Applications > customer managed, select your newly created application and fill in the following fields:
- Application metadata
- Select "Manually type your metadata values"
- Application ACS URL (Consumer URL): Your Pyramid URL with /login/callback on the end
- Application SAML audience: PyramidSAML
Assigned users and groups
Add the users and groups that will need to access Pyramid via this SAML application.
Edit attribute mappings
Under your application, select it > Actions> edit attribute mappings.
In the below example, we are mapping the user's email (${user:email}) to the “emailAddress” format. You can choose to map any value you want, however the Format should always be “emailAddress”, note that it must be sent in the subject and match the external user ID you setup in Pyramid. For further information on setting up the attributes see AWS documentation here.
Setting the provider up in Pyramid
To pull the metadata details for your new application, choose your application and click on “Edit configuration” and then on “Download” for IAM Identity Center SAML metadata file and open and copy the values into Pyramid using the Change Provider pages to capture your details.
Open the Change Provider page
- In the Admin Console, click Security > Authentication.
- From the top-right of the page, click Change Provider.
The Authentication Provider page opens with the details of your current Authentication Provider displayed.
The Change Provider page opens. You will copy the details of your new authentication provider into this page, starting by selecting your Provider.
SAML AWS Provider Details
- Provider: SAML
- Vendor: AWS
- Consumer URL: Your Pyramid URL with /login/callback on the end
- SAML Issuer: This is the entityID
- IDP URL: This is the SingleSignOnService (HTTP-POST) URL
- Logout URL: This is the SingleLogoutService (HTTP-POST) URL
- Certificate: This is the ds:X509Certificate
- External ID: Any user that you gave access to the application. It must match the value you mapped to the subject
User Provisioning Setup
At the moment, Pyramid's integration with AWS SAML does NOT include user provisioning.
Save your changes
Click Apply to start the provider change-over process. At this stage, the existing users (attached to the previous authentication system) need to be converted over.
Admins will be prompted to either:
- Delete all existing users and their local content. When users are deleted by this process, all their private data (the discoveries, publications, and so on that are stored in their My Content Folder) is "soft deleted." Soft deleted files are moved into the Deleted users content folder and can be restored by an admin if needed.
- Convert old users to the new provider (through the user conversion wizard), and keep their content
Since this exercise cannot be rolled back once the changes are committed, admins need to step through this exercise carefully.
- Click here for a detailed explanation and walkthrough of User Conversion